Claude Usage Widget.
A small always-on-top panel that shows your Claude Code usage for today — summed across every session since midnight, so it never flips between sessions. Headline spend, two cost figures, a per-model breakdown (with each model's tokens today), a live list of your recent chats with how full each one's context is, and your all-time totals — all at once. Windows only.
Claude Usage v1.15.0📅 ↻ ×
Spent Today · Cached
$480.44
If Billed Per Token:$2,256.56
Claude Cloud:
Opus$480.441.04B
Fable$14.8329.6M
Local:
qwen3:8b-32k84.2M
Context UsedRecent Cloud Chats ▾
Hearth41%410k
United Disease…95%950k
Maestro58%580k
Context UsedRecent Local Chats ▾
local test22%7.2k
All Time Usage:6.38B tokens
$5,528.96 cached·$31,343.45 per token
Local All-Time:842.1M tokens
What you're looking at. Everything you've used today, across all sessions: the big spent-today figure, the raw per-token price, and model rows split into two groups — Claude Cloud: (one row per Claude family used today) and Local: (the last 5 distinct local models used today, e.g. different Ollama tags — no cost column, since Local is never priced). It's a running daily total — it only grows and resets each morning, so it never jumps between sessions. Drag it anywhere — many people park it bottom-left.
Recent chats. Under the totals are two independent, collapsible lists — Recent Cloud Chats (up to 10 by default) and Recent Local Chats (up to 5 by default) — each named exactly as in the Claude app, with a bar for how full that chat's context window is right now (Local uses its own auto-detected window size, since local model context limits vary far more than Claude's). See every chat at a glance instead of one bar that flips when you switch chats. Hover a row for exact tokens, model, and last-active time.
Context-bar colour (each chat):
under 70%
70–89%
90%+
The honest bit. Nothing can place a widget inside the Claude Code app's left sidebar — that part of the app isn't extendable by any plugin. This is the faithful workaround: a separate floating chip that stays on top of every window and that you drag to wherever you want it. Visually it can sit right alongside the app; technically it's its own little window.
1Requirements
- Windows 10 or 11. Uses built-in Windows PowerShell + .NET WinForms — nothing to install.
- Claude Code, used at least once. The widget reads the local session transcripts Claude Code writes under
%USERPROFILE%\.claude\projects\. It never touches the network.
2Install & run
Easiest — one click. Unzip the folder, then double-click Install.cmd. It copies the widget into place, clears the “downloaded from the internet” flag so nothing gets blocked, asks whether to add a Desktop and/or Start Menu shortcut (both default Yes — just press Enter), and launches it. If Windows shows a “Windows protected your PC” box, click More info → Run anyway — it's a small, readable script.
Or run it in place. Prefer not to install? Just double-click Start Widget.vbs. The panel appears at the bottom-left with no console window. Drag it wherever you want — it remembers the spot.
It works immediately if you've used Claude Code before — it reads your existing session history. If it says “no Claude usage yet today,” just send one message in Claude Code and it populates.
3Keeping it running day to day
The widget keeps running until you close it or restart the PC. It survives sleep, so if you just leave your machine on, it'll still be there when you come back — nothing to do.
- Bring it back any time: double-click
Start Widget.vbs again — exactly the same as launching it the first time.
- Never think about it again: double-click
Add to Startup.cmd once. From then on it launches automatically every time you sign in to Windows — so the morning after a shutdown or reboot, you log in and it's already there. Remove from Startup.cmd undoes it.
Coming back the next day? If you shut down or restarted, log in and — if you ran Add to Startup.cmd — it's already running. If not, double-click Start Widget.vbs. Auto-start only kicks in at sign-in, so if you close the widget in the middle of a session it won't reappear on its own until your next login; Start Widget.vbs brings it right back.
4Move, history & close
- Move: click and drag anywhere on the panel.
- History calendar: click the calendar button in the top-right (or right-click → History (calendar)). It opens a per-day usage calendar in your browser — all-time summary cards, rolling usage cards (last 5 hours / 7 days / Fable 7 days), a heat-mapped month grid, and a Cost/Tokens toggle. Click any day to open a full breakdown of that date: by model, by hour, and every chat session individually — click a session card there to jump straight to that chat's all-time totals below. Under the grid there's also a collapsible All Chats catalog — every chat you still have logs for, as a zebra-striped list you can sort (Most recent, Name A–Z, Tokens high→low, or low→high) and collapse with a click on its header; click a row to expand its total tokens, cost, turns, active dates, and a per-model table (tokens, cost, turns, and output for each model). Your history is saved locally, so it keeps growing even after Claude Code prunes old transcripts.
- Archive a chat: right-click a chat in the recent chats section → Archive this chat. It leaves the widget's list and the calendar's chat lists, but its tokens still count in every total — nothing is deleted. Right-click → Unarchive N chats (also on the main menu) restores them. Note: archiving a chat inside Claude Code itself can't be detected automatically (that state lives in the app's internal database, not a file we can read), so archive here is manual.
- Widget settings: at the top of the calendar, change how many recent cloud chats and how many recent local chats the widget shows — Save applies both immediately (talks to a tiny
127.0.0.1-only listener the widget runs while open; never reachable off your machine), Update re-reads the widget's current values.
- Clickable cards & model chips: the calendar's summary cards and every model chip (in All Chats, a day's model bars, or Usage Windows' model mix) are clickable — they open a dedicated Tokens, Spend, Local Usage, or per-model detail page with its own trend and totals, instead of being static labels.
- Usage Windows: a button next to the calendar's title opens a page tracking your own observed usage in 5-hour / day / 7-day windows over time — since Anthropic doesn't publish the exact limits, this is the honest way to spot a pattern if they ever change — plus a Patterns section showing your all-time-high day / peak-5h / trailing-7d and how today compares. Reuses data already saved, no extra scanning.
- Refresh: click the ↻ button to re-scan right now.
- Close: click the × in the top-right, or right-click the panel → Exit.
- Right-click menu: History (calendar) Refresh now Open instructions Exit
5What the numbers mean
title
The label “Claude usage,” with a ↻ refresh button and a × close button.
Spent Today · Cached
The headline number: today's cache-aware cost, summed across every session since midnight. The realistic API estimate — see the note below.
If Billed Per Token:
The raw “sticker” price for today: every input, cache, and output token at full list rate, no cache discount. Always larger — usually several times the cached figure.
Claude Cloud: rows
Up to four rows — one per Claude family you've used today (Opus, Sonnet, Haiku, Fable), summed across all sessions. Each shows that model's cache-aware cost — lined up with where the context bar starts in the recent-chats rows below — and the total tokens it used today, right-justified. The panel grows/shrinks to fit — no empty rows.
Local: rows
Up to five rows — the last 5 distinct local models used today (e.g. different Ollama tags, if Claude Code was ever pointed at a non-Claude model), each with the total tokens it used today, right-justified. No cost column — Local is never priced, so a repeated $0.00 would just be noise.
Context Used · Recent Cloud/Local Chats
Two independent sections — your up to 10 most-recent cloud chats and up to 5 most-recent local chats by default (both configurable), each named exactly as in the Claude app (its custom or AI-generated title). The bar shows how full that chat's context window is right now — green under 70%, amber to 89%, red at 90%+ (getting close to a compaction) — with the percentage and the absolute context-token count beside it, split by a thin divider (e.g. 67% | 670k). Hover a row for the model and how long ago it was active; right-click a row to archive that chat, or click either section's header to collapse it (each remembers its own choice) — "Context Used" sits on the left, "Recent Cloud/Local Chats" is right-justified with the collapse arrow (▾/▸) to its right, the very last thing in the row. Unlike the totals above, these lists span all your recent chats, not just today's.
All Time Usage:
Near the bottom: your all-time Claude/Cloud total tokens (right-justified) and both cost estimates (cache-aware left, per-token right), summed from your saved history — the figure that grows into the millions and billions. Local (Ollama etc.) tokens are never mixed in here — different tokenizer, always $0, tracked separately, and (once you've ever used one) get their own right-justified Local All-Time: line right below it. (It reflects recorded history; opening the calendar once fills in any older days.) Just below that is the day's output / turns / sessions, spread evenly left/center/right; and on the very bottom line, right-aligned, Updated … ago (how fresh the reading is).
About “context used.” Each chat's bar is that conversation's current size (its last turn's prompt + reply) measured against the model's context window. The window is detected automatically — 200K normally, or 1M if any recent chat is bigger (the long-context beta). It answers “which of my chats is getting full and about to compact?” at a glance, without opening each one.
About the dollar figures. Both are estimates at API list prices. If you're on a Claude Max/Pro subscription you don't pay per token — your plan covers it — so read them as “what today would have cost on the pay-as-you-go API,” a sense of weight, not a bill. Spent today · cached is the realistic number (caching is part of real API billing); if billed per token shows the raw token volume's sticker price with the caching discount removed. Both include work done by any sub-agents your sessions spawned (Explore/Task/parallel helpers).
Why not the real 5-hour / weekly / Fable meters? Claude Code shows official plan meters in its /usage view (the 5-hour session limit, the weekly all-models limit, the weekly Fable limit). Those percentages come live from Anthropic's API and are never written to any local file — so an offline, transcript-only tool like this genuinely can't read them without making network calls, which would break its no-network promise. The history calendar's rolling-usage cards and Usage Windows page are the honest alternative: they sum your actual token usage in the last 5 hours / day / 7 days. They tell you how hard you've been working in those windows — they just can't know your plan's remaining percentage.
Known limitations. This tool can only read what Claude Code writes locally — it can't see Claude Design (Anthropic doesn't release token counts for it), claude.ai chat/co-work in the web app (runs entirely on Anthropic's servers, no local footprint), or reasoning effort/fast mode (not recorded in the local transcript format). This same list is at the bottom of the calendar's home page, kept up to date.
6How it works (under the hood)
Every turn, Claude Code appends your conversation — including exact token counts and a timestamp — to a transcript file under %USERPROFILE%\.claude\projects\. The widget looks at every transcript touched today (and any subagents\*.jsonl beside them), and for each one reads only the bytes appended since it last looked, keeping a per-file running total of the turns timestamped today. It sums those into one daily figure and buckets cost + output by model family. From that it paints the headline cost, one row per model used today, the raw cost, and the footer. Because it only re-reads new bytes, even a busy live session refreshes in a few milliseconds, and at local midnight the counters reset. No status line, no background service, no network — just one small program reading files that already exist.
The recent chats list works a little differently: for each of your latest chats it reads only the tail of that chat's transcript to find its current context size and its title (as the app shows it). Those tail reads are cached by the file's modified-time, so an idle second reads nothing and only the chat you're actively working in gets re-sampled.
7Tweaking it
Everything lives in usage-widget.ps1 — open it in any text editor:
- Prices: the
Get-Price function holds per-model list rates — edit if Anthropic's prices change or you want different numbers. The cache-aware cost derives cache rates from the input rate; the per-token cost uses the input rate flat.
- Row colours / order:
$FamColor and $FamOrder. Every Cloud family with usage today is shown automatically — you don't choose which. $MaxCloudFamilyRows (default 4) / $MaxLocalModelRows (default 5) cap the Claude Cloud: / Local: groups.
- Recent-chats list length:
$MaxSessionsDefault (default 10, cap $MaxSessionsCap=50) for cloud chats, $MaxLocalSessionsDefault (default 5, cap $MaxLocalSessionsCap=50) for local chats. Change either any time from the calendar's settings panel instead — it writes usage-widget-settings.json and applies immediately, no restart.
- Context window:
$ContextWindowTokens (default 0 = auto: 200K, or 1M if any recent cloud chat is bigger; tiers in $CtxWindowTiers). $LocalContextWindowTokens / $LocalCtxWindowTiers (default tiers 8K–256K) is the equivalent for local chats, kept separate since local model context sizes don't line up with Claude's.
- Rolling windows (calendar):
$Roll5hHours / $Roll7dDays (default 5 / 7) set the last-5h / last-7d windows shown as cards in the history calendar. (The panel itself no longer shows a rolling section.)
8Troubleshooting
- “no Claude usage yet today”: you haven't used Claude Code yet today, or it's just past midnight. Send a message and it appears.
- Numbers feel frozen: they only change when a new turn is written. The “updated … ago” line tells you how fresh it is.
- The cost looks big: that's the API-list estimate for the whole day, not a charge — see section 5. The “per token” figure is deliberately the larger, no-caching number.
- Only one model row: you only used one model today. Rows appear as you (or sub-agents) use more — e.g. Haiku often shows up once a sub-agent runs.
- A recent chat shows a red bar: that chat's context is nearly full (90%+) and will soon compact — nothing to fix, just a heads-up. No recent chats listed? You haven't chatted recently, or your transcripts were pruned. A chat named (untitled chat) simply hasn't been given a title yet by the app.
- Widget disappeared: double-click
Start Widget.vbs again. Only one copy runs at a time, so you can't accidentally stack duplicates.
- Windows blocked the .vbs / .cmd: right-click the file → Properties → tick Unblock (appears on files downloaded from the internet), then run it.